<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
    <head>
        <!-- $Id: NCoverFAQ.html 91 2006-01-17 23:51:02Z NCover $ -->
        <title></title>
        <meta content="Microsoft Visual Studio .NET 7.1" name="GENERATOR">
        <meta content="http://schemas.microsoft.com/intellisense/ie5" name="vs_targetSchema">
        <style> body { font-size: 10pt; font-family: Verdana; }
	p.title { font-size: 20pt; font-weight: bold; }
	.subtitle { color: maroon; }
	p.question { font-weight: bold; }
	pre { font-size: 10pt; font-family: Courier; }
	pre.usage { background-color: #F0F0F0; }
	.quote { background-color: #F0F0F0; margin-left: 36pt;}
	.method { color: maroon; font-size: 10pt; font-weight: bold; }
	.hdrcell { background-color: #DDEEFF; font-size: 10pt; }
	.datacell { background-color: #FFFFEE; text-align: right; font-size: 10pt; }
	.hldatacell { background-color: #FFCCCC; text-align: right; font-size: 10pt; }
	.box { border: 1px solid; padding: 10px; }
        </style>
    </head>
    <body>
        <P class="title">NCover FAQ</P>
        <P>If you have questions that this document does not address, contact <A href="mailto:peter@waldschmidt.com">
                Peter Waldschmidt</A>.</P>
        <P class="question">1. What is code coverage analysis?</P>
        <P class="answer">A code coverage analyzer monitors your code at runtime and 
            records information about which lines of code were executed. NCover shows each 
            sequence point in your application along with the number of times that point 
            was executed. Sequence points are generated by the compiler and stored in the 
            debug information (.pdb) files. A sequence point basically corresponds to a 
            single program statement (often a line of code) in your high-level language.</P>
        <P class="question">2. Why would I want to do code coverage analysis?</P>
        <P class="answer">Unit test suites are often used as a quality tool during the 
            development process to keep the codebase stable as it changes and expands. 
            Tools such as <A href="http://nunit.org/">NUnit</A> are often used to run and 
            report on the test suites. However, when implementing unit testing in your 
            build process, you have no way of knowing how much of your code the unit tests 
            are actually testing. This is where code coverage comes in. You can run NUnit 
            within NCover and use the code coverage report to determine which code was not 
            tested by that particular test suite.</P>
        <P class="question">3. What versions of the CLR does NCover support?</P>
        <P class="answer">At this time, NCover has only been tested on the .NET framework 
            version 1.1.4322.</P>
        <P class="question">4. What is the command line syntax for NCover?</P>
        <P class="answer">Here is the usage info from the NCover command line:</P>
        <pre class="usage">Usage: NCover /c &lt;command line&gt; [/a &lt;assembly list&gt;]

/c Command line to launch profiled application.
/a List of assemblies to profile. i.e. "MyAssembly1;MyAssembly2"
/v Enable verbose logging (show instrumented code)
        </pre>
        <UL>
            <LI>
            The /c command-line argument is required and specifies the command-line of the 
            .NET application you want to analyze.
            <li>
            The /a command-line argument specifies the assemblies that you want to analyze. 
            NCover can only analyze assemblies that have .pdb files included with them. If 
            you do not specify the /a argument, NCover will attempt to analyze every loaded 
            assembly that has debug information available.
            <li>
                The /v command-line argument makes the profiler emit all the original IL and 
                modified IL instructions to the coverage log. This is useful for debugging 
                purposes. Beware that this can make your coverage log file very large!
            </li>
        </UL>
        <P class="question">5. Does NCover required a special compilation step for my code?</P>
        <P class="answer">No. Some code coverage tools change your source code and force 
            you to recompile it into a special build.&nbsp; NCover is designed to&nbsp;work 
            on shipping code.&nbsp; NCover uses the .NET Framework profiling API to monitor 
            your code. It does require build symbols, but can be run on release code 
            without any modifications.</P>
        <P class="question">6. How does NCover work?</P>
        <P class="answer">NCover uses the .NET Framework profiler API to monitor an 
            application's execution. When a method is loaded by the CLR, NCover retrieves 
            the IL and replaces it with instrumented IL code.&nbsp; NCover does not change 
            your original IL code, it simply inserts new code to update&nbsp;a visit 
            counter at each sequence point.&nbsp; After&nbsp;the .NET&nbsp;process 
            shuts&nbsp;down, the profiler outputs statistics to a file in the current 
            directory.
        </P>
        <P class="question">7. How do I analyze an ASP.NET application with NCover?</P>
        <P class="answer"><STRONG>xmspc</STRONG> got this to work on ASP.NET. See his post 
            on the message board for more information. Here are the basics for getting it 
            to work on Windows XP.
        </P>
        <div class="quote">
            <P class="answer">
                1) Ensure the NCoverLib COM component is registered (setup does this, but you 
                can manually register it with regsvr32 if you wish).
            </P>
            <P class="answer">
                2) Set the machine-wide COR profiling environment variables (or find some other 
                way to get them set in the aspnet_wp.exe's environment):
                <BR>
                &nbsp;&nbsp;COR_ENABLE_PROFILING=1
                <BR>
                &nbsp;&nbsp;COR_PROFILER=CvrLib.CoverageProfiler
            </P>
            <P class="answer">3) Create %windir%\System32\Coverage.log and 
                %windir%\System32\Coverage.xml and grant .\ASPNET read+write+modify permission 
                to these 2 files only.
            </P>
            <P class="answer">4) Force a restart of IIS so aspnet_wp.exe picks up the new 
                environment variables.&nbsp;Coverage info will be written to the System32 
                directory.
            </P>
            <P class="answer">All ASP.Net processes (on Windows XP for sure, don't know about 
                Windows 2003) use %windir%\System32 as their working dir, therefore if multiple 
                processes are running they will stomp over the Coverage files.
            </P>
            <P class="answer">...would be nice if NCover used AppDomain basedir and/or value 
                from app config file to set output file dir...
            </P>
        </div>
        <P class="question">8. What is the output of NCover?</P>
        <P class="answer">NCover writes three files to the directory after analysis 
            completes.
            <ul>
                <li>
                Coverage.log - This file is a log of the events and messages from the profiler 
                during the analysis process. Most of the time, error messages are recorded in 
                this log. If you enable verbose logging, the coverage log will contain 
                disassembly of the original and instrumented IL code.
                <li>
                Coverage.xml - This file is the analysis output of NCover. You can see an 
                example of the output below.
                <LI>
                    Coverage.xsl - This file is a simple XML transformation that makes the XML 
                    output easily readable.
                </LI>
            </ul>
            <span class="subtitle">Example XML output</span>
            <div class="box"><pre>&lt;method class="NCoverTest.ClassLoaded" name="HasDeadCode"&gt;
    &lt;seqpnt document="C:\Dev\Utilities\ncover\NCoverTest\NCoverTest.cs"
            column="13" line="48" endcolumn="58" endline="48" visitcount="1" /&gt; 
    &lt;seqpnt document="C:\Dev\Utilities\ncover\NCoverTest\NCoverTest.cs" 
            column="13" line="49" endcolumn="22" endline="49" visitcount="1" /&gt; 
    &lt;seqpnt document="C:\Dev\Utilities\ncover\NCoverTest\NCoverTest.cs" 
            column="17" line="50" endcolumn="24" endline="50" visitcount="1" /&gt; 
    &lt;seqpnt document="C:\Dev\Utilities\ncover\NCoverTest\NCoverTest.cs" 
            column="13" line="51" endcolumn="48" endline="51" visitcount="0" /&gt; 
    &lt;seqpnt document="C:\Dev\Utilities\ncover\NCoverTest\NCoverTest.cs" 
            column="9" line="52"  endcolumn="10" endline="52" visitcount="0" /&gt; 
&lt;/method&gt;</pre>
            </div>
        <p></p>
        <span class="subtitle">Example transformed output</span>
        <div class="box">
            <DIV class="method">NCoverTest.ClassLoaded.HasDeadCode</DIV>
            <TABLE id="Table1" borderColor="black" cellSpacing="0" cellPadding="3" border="1">
                <TBODY>
                    <TR>
                        <TD class="hdrcell">Visit Count</TD>
                        <TD class="hdrcell">Line</TD>
                        <TD class="hdrcell">Column</TD>
                        <TD class="hdrcell">End Line</TD>
                        <TD class="hdrcell">End Column</TD>
                        <TD class="hdrcell">Document</TD>
                    </TR>
                    <TR>
                        <TD class="datacell">1</TD>
                        <TD class="datacell">48</TD>
                        <TD class="datacell">13</TD>
                        <TD class="datacell">48</TD>
                        <TD class="datacell">58</TD>
                        <TD class="datacell">C:\Dev\Utilities\ncover\NCoverTest\NCoverTest.cs</TD>
                    </TR>
                    <TR>
                        <TD class="datacell">1</TD>
                        <TD class="datacell">49</TD>
                        <TD class="datacell">13</TD>
                        <TD class="datacell">49</TD>
                        <TD class="datacell">22</TD>
                        <TD class="datacell">C:\Dev\Utilities\ncover\NCoverTest\NCoverTest.cs</TD>
                    </TR>
                    <TR>
                        <TD class="datacell">1</TD>
                        <TD class="datacell">50</TD>
                        <TD class="datacell">17</TD>
                        <TD class="datacell">50</TD>
                        <TD class="datacell">24</TD>
                        <TD class="datacell">C:\Dev\Utilities\ncover\NCoverTest\NCoverTest.cs</TD>
                    </TR>
                    <TR>
                        <TD class="hldatacell">0</TD>
                        <TD class="datacell">51</TD>
                        <TD class="datacell">13</TD>
                        <TD class="datacell">51</TD>
                        <TD class="datacell">48</TD>
                        <TD class="datacell">C:\Dev\Utilities\ncover\NCoverTest\NCoverTest.cs</TD>
                    </TR>
                    <TR>
                        <TD class="hldatacell">0</TD>
                        <TD class="datacell">52</TD>
                        <TD class="datacell">9</TD>
                        <TD class="datacell">52</TD>
                        <TD class="datacell">10</TD>
                        <TD class="datacell">C:\Dev\Utilities\ncover\NCoverTest\NCoverTest.cs</TD>
                    </TR>
                </TBODY>
            </TABLE>
        </div>
        <P></P>
        <P class="question">9. How do you test NCover?</P>
        <P class="answer">Unfortunately, all the original testing was done with production 
            code that cannot be published. I have started on a test suite called 
            NCoverTest. It is pretty anemic right now, but feel free to chip in and 
            contribute some tests.</P>
    </body>
</html>
